docs: add agent files #5412
docs: add agent files #5412
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
There was a problem hiding this comment.
Greptile Summary
This PR adds two comprehensive documentation files, AGENTS.md and CLAUDE.md, designed to serve as guidance documents for AI code agents working on the Onyx repository. Both files contain nearly identical content providing essential context about the codebase architecture, development patterns, and operational procedures.
The documentation covers key areas including:
- Local development setup with virtual environment activation (
workon onyx) - Detailed Celery worker architecture covering 8 different worker types (primary, light, heavy, monitoring, etc.)
- Database and API conventions using FastAPI with specific patterns for task definition using
@shared_taskdecorators - Multi-tenant support architecture and security considerations
- Comprehensive testing strategies covering unit tests, integration tests, background job tests, and API tests
- Code quality standards and development best practices
The files appear to consolidate tribal knowledge and best practices into centralized reference points, reducing the learning curve for AI agents working with the complex Onyx codebase that spans multiple services (Celery background workers, FastAPI backend, Next.js frontend). This addresses a common challenge in AI-assisted development where agents need deep contextual understanding of project conventions and architectural patterns.
PR Description Notes:
- The PR description sections are left as placeholder templates and should be filled in with actual testing details and change descriptions
Confidence score: 4/5
- This PR is safe to merge with minimal risk as it only adds documentation files without changing any functional code
- Score reflects that while the documentation is comprehensive and well-structured, there is significant duplication between the two files that could be consolidated
- Pay attention to the duplicate content between
AGENTS.mdandCLAUDE.md- consider whether both files are necessary or if they could be merged into a single comprehensive guide
2 files reviewed, 1 comment
| #### Important Notes | ||
|
|
||
| **Defining Tasks**: | ||
| - Always use `@shared_task` rather than `@celery_app` |
There was a problem hiding this comment.
syntax: The backtick around @celery_app should probably be @celery_app.task to be more specific about what to avoid.
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
There was a problem hiding this comment.
1 issue found across 2 files
Prompt for AI agents (all 1 issues)
Understand the root cause of the following 1 issues and fix them.
<file name="AGENTS.md">
<violation number="1" location="AGENTS.md:105">
This instruction contradicts current FastAPI patterns in the repo and could cause inconsistencies; align guidance with existing use of response_model.</violation>
</file>
React with 👍 or 👎 to teach cubic. Mention @cubic-dev-ai to give feedback, ask questions, or re-run the review.
| - Put tasks under `background/celery/tasks/` or `ee/background/celery/tasks` | ||
|
|
||
| **Defining APIs**: | ||
| When creating new FastAPI APIs, do NOT use the `response_model` field. Instead, just type the |
There was a problem hiding this comment.
This instruction contradicts current FastAPI patterns in the repo and could cause inconsistencies; align guidance with existing use of response_model.
Prompt for AI agents
Address the following comment on AGENTS.md at line 105:
<comment>This instruction contradicts current FastAPI patterns in the repo and could cause inconsistencies; align guidance with existing use of response_model.</comment>
<file context>
@@ -0,0 +1,295 @@
+- Put tasks under `background/celery/tasks/` or `ee/background/celery/tasks`
+
+**Defining APIs**:
+When creating new FastAPI APIs, do NOT use the `response_model` field. Instead, just type the
+function.
+
</file context>
Description
[Provide a brief description of the changes in this PR]
How Has This Been Tested?
[Describe the tests you ran to verify your changes]
Backporting (check the box to trigger backport action)
Note: You have to check that the action passes, otherwise resolve the conflicts manually and tag the patches.
Summary by cubic
Add AGENTS.md and CLAUDE.md with clear guidance for code agents working in this repo. They document local setup, Celery workers, API/DB conventions, migrations, testing, logs, security, and UI/UX patterns to reduce errors and speed up work.